package rbac.service;

import java.util.Collection;
import java.util.List;

import rbac.entity.RbacRole;
import rbac.entity.RbacUserGroup;
import rbac.exception.EntityDoNotExistException;


/**
 * RBAC service 接口. 负责在 service 层处理<strong>用户组</strong>信息.
 * 
 * @author Huadi
 * @author Zoufengyang
 */
public interface UserGroupService {

	/**
	 * 通过用户 ID 获取 <code>RbacUserGroup</code>.
	 * 
	 * @param id
	 *            用户 ID.
	 * @return <code>RbacUserGroup</code> 类型的对象. 如果不存在, 返回 <code>null</code>.
	 */
	RbacUserGroup getUserGroup(Integer id);

	/**
	 * 获取所有 <code>RbacUserGroup</code> 实体.
	 * 
	 * @return 所有 <code>RbacUserGroup</code> 实体列表.
	 */
	List<RbacUserGroup> getAllUserGroups();

	/**
	 * 持久化一个 <code>RbacUserGroup</code> 实体.
	 * 
	 * @param userGroup
	 *            要持久化的实体.
	 */
	void save(RbacUserGroup userGroup);

	/**
	 * 修改一个 <code>RbacUserGroup</code> 实体.
	 * 
	 * @param userGroup
	 *            要修改的实体.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void update(RbacUserGroup userGroup) throws EntityDoNotExistException;

	/**
	 * 删除一个用户组.
	 * 
	 * @param userGroup
	 *            用户组实体.
	 */
	void delete(RbacUserGroup userGroup);

	/**
	 * 删除一个用户组.
	 * 
	 * @param id
	 *            用户组 ID.
	 */
	void delete(Integer id);

	/**
	 * 将一个角色的权限赋予一个用户组.
	 * 
	 * @param role
	 *            角色实体.
	 * @param userGroup
	 *            用户组实体.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantRoleToUserGroup(RbacRole role, RbacUserGroup userGroup)
			throws EntityDoNotExistException;

	/**
	 * 将一个角色的权限赋予一个用户组.<br>
	 * 鼓励使用实体进行添加删除操作, <strong>使用此方法会导致数据库 IO 过多</strong>.
	 * 
	 * @param roleId
	 *            角色 ID.
	 * @param userGroupId
	 *            用户组 ID
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantRoleToUserGroup(Integer roleId, Integer userGroupId)
			throws EntityDoNotExistException;

	/**
	 * 
	 * @param userGroupId
	 *            用户组实体 ID.
	 * @param selectedRoles
	 *            要批量添加的角色 ID.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void grantRoleToUserGroup(Integer userGroupId, List<Integer> selectedRoles)
			throws EntityDoNotExistException;

	/**
	 * 从一个用户组收回一个角色的权限.
	 * 
	 * @param role
	 *            角色实体.
	 * @param userGroup
	 *            用户组实体.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	void revokeRoleFromUserGroup(RbacRole role, RbacUserGroup userGroup)
			throws EntityDoNotExistException;

	/**
	 * 从一个用户组收回一个角色的权限.<br>
	 * 鼓励使用实体进行添加删除操作, <strong>使用此方法会导致数据库 IO 过多</strong>.
	 * 
	 * @param roleId
	 *            角色 ID.
	 * @param userGroupId
	 *            用户组 ID.
	 * @throws EntityDoNotExistException
	 *             当指定实体不存在时.
	 */
	@Deprecated
	void revokeRoleFromUserGroup(Integer roleId, Integer userGroupId)
			throws EntityDoNotExistException;

	/**
	 * 批量添加用户到用户组中.
	 * 
	 * @param userIds
	 *            用户名集合.
	 * @param userGroupId
	 *            用户组 ID.
	 */
	void addUsersToUserGroup(Collection<Integer> userIds, Integer userGroupId);

}
